home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / AmigaSystem / AmiStart / ToolsSDK.lha / developer.doc next >
Text File  |  2002-06-15  |  16KB  |  347 lines
  1. Amistart Tool creating Developer Documentation:
  2.  
  3. First of all:
  4.     excuse the very bad description, it was fast made and my english is very bad
  5.  
  6. This documentation describes how to implement AmiStart Tools, the
  7. AmiStart Tools developer Kit is based on the "Lib37x" available on AMINET done by
  8. Andreas R. Kleinert. This means you could spread Tool-libraries but you can't
  9. spread the sourcecode of them without asking Andreas R. Kleinert for permission
  10.  
  11.  
  12. What are Tools?
  13.  
  14. Tools have a library equal structure, all Tools with the same Version must
  15. implement all Functions for this Version.
  16.  
  17. Tools are information servers added to the right border on the TaskBar, for example
  18. Memory usage meters, cpu-meter and so on, but they also can do actions.
  19.  
  20. AmiStart calls defined functions to get informations about the Tool, how to initialize them and
  21. how to send Messages to them.
  22.  
  23.  
  24. How to start?
  25.  
  26. First think about what version of a Tool you really need, see the Version
  27. Tool Description below. For example if you only need Version 39 Functions
  28. set VERSION in the File LibInit.c to 39 (all tools must at least have
  29. Version 39, coz this is the initial Version). Unsing a Version prevents AmiStart
  30. from calling Functions of upper Versions, but all Functions must be implemented
  31. for this Version and all of its parent.
  32. Change the EXLIBNAME, REVISION and Copyright notice in LibInit.c.
  33. Implement all Tool Functions for your specific Version in the File ModuleFuncs.c
  34. Finally compile StartUp.c LibInit.c and ModuleFuncs.c link them in this order without
  35. any StartUp Code (library linking) and finnaly link the amiga.lib, name the output
  36. "toolname".tool, where toolname is the same name as defined in libInit.c named
  37. EXLIBNAME.
  38.  
  39. The resulting tool could be copied to any location, preferring the "modules" directory in the AmiStart
  40. directory, or in a directory "modules" inside the DATAPATH defined by the DATAPATH ToolType..
  41.  
  42. NOTE: i have only tested the vbcc makefile!
  43.  
  44. How a Tool Work.
  45.  
  46. A Tool doesn't have a specific data structure you will be free to implement your
  47. data as you need it, all requests will be done by specific Functions with fixed
  48. parameters and fixed results, this functions must be implement.
  49.  
  50. Further your Tool must implement a message port, after initializing the Tool AmiStart send messages
  51. to the Tools Port, a Tool will get Space onto the TaskBar and can use it to display informations
  52. as well as it can launch for Mouse/Timer events.
  53.  
  54. I recommend to use this example source to build your own Tool, a Tool consits of several
  55. functions for initializing the tool, it must implement a MessagePort to communicate with
  56. AmiStart and therefore it must be a own thread (task).
  57.  
  58. AmiStart initializes the tool in the following way:
  59.  
  60.  OpenTool()->NewTool()->GetToolWidth()->GetToolHeight()->GetToolPort()->InitTool()
  61.  
  62.  after NewTool() is called you have to create the Task and this Task must create the Message port and stop all
  63.  activities. You will get a ASCLASS_START Message to activate your tool, to remove your Tool you will get a
  64.  ASCLASS_STOP message (this only should stop your Tool not remove it, there are also other reasons to recive this
  65.  message).
  66.  
  67.  The DisposeTool() method will be called to remove your Tool.
  68.  
  69. ******************************************************************************************
  70. ******************************************************************************************
  71.  
  72.  
  73. Which Functions must be implement?
  74.  
  75. Note: Newer Versions must implement previous Version Functions.
  76. Note: a Tool is library based, so you must make all functions reentrant.
  77.  
  78. A Function has the following Structure:
  79.  
  80.     RETURNTYPE FunctionName(PAREMETER1, PARAMETER2, ...)
  81.  
  82.     while PARAMETERS are all filled by AmiStart,
  83.  
  84. ******************************************************************************************
  85.  
  86. Version 39: (initial Version)
  87.  
  88.     BOOL OpenTool()
  89.  
  90.         Initial a Tool.
  91.  
  92.         INPUTS: none
  93.         OUTPUT: BOOL, if FALSE initialization fails and the tool will not be used
  94.  
  95.         Description:
  96.             AmiStart calls this command to initialize your tool-library, you can open libs and other resources, but
  97.             you can launch a tool multiple, so make sure, coz tools are libraries, you will not open them multiple
  98.             for example use global library variables initialize them by NULL and test it before. (See the example tool)
  99.  
  100.         See: CloseTool()
  101.  
  102.     VOID CloseTool()
  103.  
  104.         Opposit of OpenTool().
  105.  
  106.         INPUTS: none.
  107.         OUTPUT: none.
  108.  
  109.         Description:
  110.             Be sure to make this Function "call save", coz it will be called
  111.             even if OpenTool() fails.
  112.             Do some cleanup here for example closing libs you have opened in OpenTool().
  113.  
  114.         See: OpenTool()
  115.  
  116.     STRPTR ToolInfo()
  117.  
  118.         Get a short info string for this Tool.
  119.  
  120.         INPUTS: none
  121.         OUTPUT: STRPTR a pointer to a Tool Info String.
  122.  
  123.         Description:
  124.             AmiStart calls this function to get a (very) short (single line) Info Text.
  125.             Use a constant string!!
  126.  
  127.     APTR NewTool(APTR prefs = REG(a0), APTR pool = REG(a1))
  128.  
  129.         create a new Tool.
  130.  
  131.         INPUTS: prefs   Pointer to optional prefs data saved in the AmiStart prefs file or NULL
  132.                 pool    A Pointer to an exec memory pool the tool could use to prevent memory fragmantation, you could
  133.                         use AllocVec/AllocMen instead.
  134.                         Memory flags are MEMF_ANY|MEMF_CLEAR, so you can be sure to get memory filled with zero bytes.
  135.         OUTPUT: APTR    tool specific data, is passed to nearly all Tool functions by AmiStart, therefore you must return a
  136.                         non NULL value!
  137.  
  138.         Description:
  139.             Once AmiStart is loaded and a Tool is initialized by OpenTool(), AmiStart calls this Function, you have to
  140.             initialize your default setup and create your task (for the Message handler)
  141.             Return a pointer to a struct or something else, this Data will be used to get Infos about your tool it will be
  142.             passed to DataRetieving functions.
  143.             The prefs data will be passed from AmiStart, assume your tool has a prefs window and you like to save the prefs, there
  144.             are several ways, a nice way is to save it within the AmiStart prefs file. Therefore AmiStart will call each time
  145.             the user wants to save the configuration the two GetToolPrefs/Size functions and save this data within the prefs file.
  146.             you will get a pointer to this data (you must create a copy of it), or NULL to use a default setup.
  147.             see the demo source.
  148.  
  149.         See: DisposeTool(), GetToolPrefs(), GetToolPrefsSize()
  150.  
  151.     void DisposeTool(APTR tool = REG(a0))
  152.  
  153.         opposite of NewTool()
  154.  
  155.         INPUTS: tool    return value from NewTool()
  156.  
  157.         Descrption:
  158.                 cleanup all allocations done by InitTool(), also you must remove your task.
  159.                 Before you remove your task it have to delete the MessagePort.
  160.  
  161.         See: InitTool()
  162.  
  163.     UWORD ToolWidth(APTR tool = REG(a0), UWORD width = REG(d0))
  164.  
  165.         AmiStart calls this to find out your Tool width.
  166.  
  167.         INPUTS: tool    returnstatement from NewTool()
  168.                 width   AmiStart gives a suggestion, but you can use your preferred width
  169.         OUTPUT: UWORD   width AmiStart will alloc for your tool.
  170.  
  171.         Description:
  172.             AmiStart needs to know how many space your Tool need on the TaskBar this function will be called
  173.             to figure out the Width, ToolHeight() will be called first!
  174.  
  175.         See: ToolHeight()
  176.  
  177.     UWORD ToolHeight(APTR tool = REG(a0), UWORD height = REG(d0))
  178.  
  179.         AmiStart calls this to find out your Tool height.
  180.  
  181.         INPUTS: tool    returnstatement from NewTool()
  182.                 height  AmiStart gives a suggestion, but you can use your preferred height
  183.         OUTPUT: UWORD   height AmiStart will alloc for your tool.
  184.  
  185.         Description:
  186.             AmiStart needs to know how many space your Tool needs on the TaskBar this function will be called
  187.             to figure out the Height, it will be called before ToolWidth()!
  188.  
  189.         See: ToolWidth()
  190.  
  191.     ULONG GetToolFlags(APTR tool = REG(a0))
  192.  
  193.         Amistart calls this to find out your Tool Flags.
  194.  
  195.         INPUTS: tool    returnstatement from NewTool()
  196.         OUTPUT: ULONG   Flags for your Tool.
  197.  
  198.         Description:
  199.             You have to return your Tool Flags, possible flags are
  200.  
  201.             TOOLS_FLAG_FMOUSE   ,   your Tool will recieve Mouse Messages (if the pointer is over your Tool)
  202.             TOOLS_FLAG_FTIMER   ,   your Tool will recieve Timer Messages (a very simple timer, you should use the timer-device instead)
  203.             TOOLS_FLAG_NOSETUP  ,   set this Flag if your Tool does not have a setup window.
  204.  
  205.     struct MsgPort *GetToolPort(REG(a0) Tool *tool)
  206.  
  207.         Amistart calls this to find out yours Tool Message Port.
  208.  
  209.         INPUTS: tool    returnstatement from NewTool()
  210.         OUTPUT: MsgPort pointer to your Tools MessagePort
  211.  
  212.         Description:
  213.             AmiStart needs a Tools-Msg-Port to communicate with, use this to let AmiStart know where to find it.
  214.             This Msg Port should be private, don't use AddPort to make it public
  215.  
  216.  
  217.     UWORD GetToolBufferType(APTR tool = REG(a0))
  218.  
  219.         Return the Display Buffer Type of your tool
  220.  
  221.         INPUTS: tool    returnstatement form NewTool()
  222.         OUTPUT: UWORD   type of the graphics Buffer for your Tool AmiStart has to alloc.
  223.  
  224.         Description:
  225.             to Display any informations on the TaskBar you need access to the Display.
  226.             AmiStart does not allow direct access to the Graphics resources instead of this
  227.             you will get two equal Buffers, one for drawing and one for buffering, the buffering Buffer is
  228.             filled with the TaskBar background (also the drawing buffer). You can copy the 2nd buffer into the
  229.             drawing buffer to restore the TaskBar background.
  230.             AmiStart supports two Buffer Types:
  231.  
  232.                 TOOLS_TYPE_BITMAP   you will get a BitMap Buffer you can attach it to a rastport and
  233.                                     use System functions for drawing into it.
  234.                                     Note on True/HiColor Workbench screens you will get True/HiColor bitmaps!
  235.                                     Use bltbitmap to copy the 2nd buffer to the first buffer for restoring the background.
  236.                                     NOTE: This way is not well tested!!
  237.  
  238.                 TOOL_TYPE_TRUECOLOR you will get two TrueColor buffers, each Pixel is represented by a ULONG (32Bit) in the
  239.                                     ARGB Format (A=Alpha, R=RED, G=GREEN, B=BLUE), the buffer is width*height*4 Bytes large,
  240.                                     use a loop or CopyMem to copy the 2nd to the 1st buffer to restore your Background.
  241.  
  242.     UWORD ToolSetup(APTR tool = REG(a0), UWORD mousex = REG(d0), UWORD mousey = REG(d1))
  243.  
  244.         AmiStart calls this to open your Tool Setup Window
  245.  
  246.         INPUTS: tool    returnstatement from NewTool()
  247.                 mousex  only if you want to open your window around the mouse
  248.                 mousey  ...
  249.         OUTPUT: UWORD   in V39 zero should be returned.
  250.  
  251.         Description:
  252.             This function will be called if the user will setup your tool.
  253.             NOTE: only possible if you clear the TOOLS_FLAG_NOSETUP flag
  254.  
  255.         See: GetToolPrefs(), GetToolPrefsSize(), GetToolFlags()
  256.  
  257.     APTR GetToolPrefs(APTR tool = REG(a0))
  258.  
  259.         if you want to save your tool Prefs within the amistart-prefs file.
  260.  
  261.         INPUTS: tool    returnstatement form NewTool()
  262.         OUTPUT: APTR    pointer pointing to your prefs or NULL.
  263.  
  264.         Description:
  265.             if your Tool supports a setup window, you propably need to save this settings, you can use this
  266.             to return a pointer to your prefs struct.
  267.             The data will be requested and encoded by AmiStart while saving your prefs. It will be passed to
  268.             your Tool while startup AmiStart (by NewTool()).
  269.  
  270.         See: NewTool(), ToolSetup(), GetToolPrefsSize()
  271.  
  272.     int GetToolPrefsSize(APTR tool = REG(a0))
  273.  
  274.         AmiStart calls this to recieve your prefs data size
  275.  
  276.         INPUTS: tool    returnstatement from InitModule()
  277.         OUTPUT: int     lenght of your prefs buffer.
  278.  
  279.         Description:
  280.             Before saving your tool prefs AmiStart needs the size of this data, return the length of it or ZERO.
  281.             Note, coz the prefs are encoded and saved within the AmiStart setup-file your prefs should be very small
  282.             (arround 200 Bytes)
  283.  
  284.         See: GetToolPrefs()
  285.  
  286.     void InitTool(APTR tool = REG(a0), APTR bm = REG(a1), APTR buffer = REG(a2), APTR hook = REG(a3), APTR t = REG(a4))
  287.  
  288.         AmiStart calls this to setup your display buffers.
  289.  
  290.         INPUTS: tool        returnstatement from NewTool()
  291.                 bm          pointer to your 1st display buffer
  292.                 buffer      pointer to your 2nd display buffer
  293.                 hook        a callback Hook you have to call to display your Tool
  294.                 t           a typeless pointer you have to pass to the hook as the Object
  295.         OUTPUT: none
  296.  
  297.         Description:
  298.             After loading, launching and setup your tool (you will recieve a STOP message before), this
  299.             function will be called to pass pointers to the graphics buffers and the paint hook to your Tool.
  300.             Buffers are from the Type of GetToolBufferType().
  301.             This procedure could be called each time after a STOP Message!!!!
  302.             the 1st Buffer is only to be used for restoring the Background, the 2nd will be used by the
  303.             callback-hook to paint your Tool.
  304.  
  305.         See: GetToolBufferType()
  306.  
  307. *************************************************************************************
  308.  
  309. Version 40: (not yet defined)
  310.  
  311.  
  312.  
  313. *************************************************************************************
  314.  
  315. How to implement your MessagePort:
  316.  
  317.     Create a nonpublic Message-port via CreateMsgPort() and AmiStart will ask it's address via
  318.     GetToolPort().
  319.  
  320.     AmiStart will send a asMessage each Time a Event occur.
  321.  
  322.     the asMessage.class member will get one of the following codes:
  323.  
  324.         ASCLASS_MOUSE   for mouse events, like mousemovements
  325.         ASCLASS_TIMER   for timer events for timer events (very limited)
  326.         ASCLASS_START   AmiStart requests your Tool to Start (see below)
  327.         ASCLASS_STOP    AmiStart requests your Tool to Stop (see below)
  328.  
  329.         ASCLASS_MOUSE:  mousemove events, only created if you set the TOOLS_FLAG_FMOUSE flag in GetToolFlags()
  330.                         in this case you will get the x, y coordinates and the qualifier mask in x, y and code.
  331.         ASCLASS_TIMER:  you will get this Message in periodic loops (only if you set the TOOLS_FLAG_TIMER flag
  332.                         in GetToolFlags(), this Timer stops in many cases (for example during Filesystem operations).
  333.         ASCLASS_START:  this message only tells you that your Tool could manipulate the Graphics-Buffers (InitTool()), and
  334.                         that you can call the paint-Hook. You can do other things without waiting for this Message.
  335.                         You will always get this Message after InitTool(), but you can get it in any other Cases.
  336.         ASCLASS_STOP:   if this Message is send, you must stop manipulating the image-buffers and to call the paint-Hook (
  337.                         set by InitTool()).
  338.                         This Message should only be replyed after you have stopped the access to this buffers, coz AmiStart
  339.                         could remove this Buffers after this Message, also AmiStart could remove your Tool (via DisposeTool()).
  340.                         You can also get a InitTool() call after this message to reinitialize your image-buffers.
  341.  
  342.  
  343. Finally:
  344.     post me a message, if something is unclear or you need help, or you have some suggestions.
  345.  
  346.     Darius Brewka
  347.     d.brewka@freenet.de